2. how to use the cairotft module

2.1. simple usage

Basic use is to simply subclass cairotft.tft.TftDisplay and overwrite the draw_interface method:

from cairotft import tft


class MyDisplay(tft.TftDisplay):

    """Custom display class."""

    def draw_interface(self, ctx):
        """draw the full interface.

        :param ctx: the cairocffi context.
        :type ctx: :class:`cairocffi.Context`
        """
        # background
        self.blank_screen(ctx=ctx,
                          color=(0.5, 0.5, 0.5, 1),
                          blit=False)

        # draw red a rectangle inside the screen
        ctx.set_source_rgba(1, 0, 0, 1)
        ctx.rectangle(50, 50, self.width - 50 * 2, self.height - 50 * 2)
        ctx.fill()

        # display on the actual screen
        self.blit()

if __name__ == '__main__':
    disp = MyDisplay()
    disp.run()

Note

you may need to be root to access to the framebuffer device.

2.1.1. Some Explanations

• you can see that TftDisplay provides some basic method to interact with the screen. In line 15 self.blank_screen repaint the whole screen with the selected color. (more about blit=False later)

• by default, TftDisplay automatically discover the screen size. you can access to the size (in pixels) with self.width and self.height properties.

  We use that capability for drawing the second rectange on line 21.

• at the end of the draw_interface method, we call self.blit(): By default, the loop calls self.draw_interface with a cairo context pointing to a memory buffer, not the actual screen buffer (this is called double buffering).

  Calling self.blit() copy the content of the memory buffer into the screen buffer (and this is only at that time that the screen is showing something)

  Note

  currently, you’re responsible of calling self.blit() when you want to repaint the screen. You can call self.blit() when you want, but beware of the performances (of your system and of your screen)

• On this example, the screen is drawed only one time (then the event loop is only looping forever without doing anything). We’ll cover this on later examples, but you’re also responsible to handle events in the event loop. Events may draw/redraw some object and then call blit()

2.1.2. Run

you can run this simple example from the cairotft main dir:

sudo python docs/examples/simple/simple.py

This will start the program on /dev/fb0. To see something, you’ll need to switch on a linux console (if you’re currently under X):

• hit: CTRL + ALT + F2

• log-in and go to the cairotft directory

• acivate your virtualenv:

  source ~/.virtualenvs/cairotft/bin/activate
  

• launch the sample program:

  sudo python docs/examples/simple/simple.py
  

• it should display a big red rectangle on top of a grey screen

• hit CTRL + c to terminate the program

• hit again CTRL + ALT + F7 (or sometimes, depending on you system: CTRL + ALT + F1) to go back to X

• if CTRL + ALT + Fx does not work on your system, you can use the chvt command:

  sudo chvt 7
  

  or:

  sudo chvt 1
  

  to go back into X

2.1.3. Result

2.2. widgets

2.2.1. blinking icon widget

blink icon is a simple widget displaying a blinking svg icon.

Here is a sample usage:

import cairocffi as cairo

from cairotft import svg_image
from cairotft import tft
from cairotft import widgets


class MyDisplay(tft.TftDisplay):

    """Custom display class."""

    def __init__(self, interface='/dev/fb0', cairo_format=cairo.FORMAT_ARGB32,
                 fps=None):
        """Initialisation of the class.

        see :class:`cairotft.widgets.blink_icon.BlinkIcon` for api details.

        Instanciates the blink icon.
        """
        super().__init__(interface=interface,
                         cairo_format=cairo_format,
                         fps=fps)

        # instanciates a blink icon
        self.icon = widgets.BlinkIcon(
            display_object=self,
            pos_x=10,
            pos_y=10,
            width=70,
            height=70,
            svg_icon=svg_image.SVGImage('icon.svg'),
            background_color=(0.5, 0.5, 0.5, 1),
            on_time=0.2,
            off_time=0.8)

    def draw_interface(self, ctx):
        """draw the full interface.

        :param ctx: the cairocffi context.
        :type ctx: :class:`cairocffi.Context`
        """
        # background
        self.blank_screen(ctx=ctx,
                          color=(0.5, 0.5, 0.5, 1),
                          blit=False)

        # start to blink
        self.icon.start(ctx)

        # display on the actual screen
        self.blit()

if __name__ == '__main__':
    disp = MyDisplay()
    disp.run()

Note

you may need to be root to access to the framebuffer device.

2.2.1.1. Some Explanations

In addition to the simple example, we override the __init__() in order to instanciate a cairotft.widgets.blink_icon.BlinkIcon object.

Then in draw_interface we starts the blinking.

That’s all.